home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / tex / filters.zip / FILTERS.DOC < prev    next >
Text File  |  1986-11-27  |  9KB  |  242 lines
  1.  
  2. Documentation for the DOS 2.1 (and probably 2.0) filters
  3.  
  4.         Upper   | translate all lowercase characters to uppercase
  5.         Lower   | translate all uppercase characters to lowercase
  6.         Snglspc | removes extra blank lines from a file
  7.         Unique  | deletes multiple occurances from a sorted list
  8.         Trunc   | truncates a line at first matching char (or space)
  9.         Fecho   | echoes standard input to screen (great for debugging)
  10.         Translat| puts each word of a file onto a separate line.
  11.         Feed    | reads a filespec and sends files to standard output
  12.         Forclean| takes a fortran source and deletes comments and labels
  13.  
  14. ========================================================================
  15.  
  16. Filters in general:
  17.  
  18.         In case you have never played with MORE, FIND, or SORT in
  19.         DOS 2.0 and DOS 2.1, here is a brief explanation of what they
  20.         are and what they do.
  21.  
  22.         Filters are special programs that always read their data from
  23.         something called "standard input" and send their output to
  24.         "standard output".  Standard input is usually the keyboard, and
  25.         standard output is usually the screen.  However, both of these
  26.         can be "redirected" wherever you want them to go using the
  27.         "<" and ">" symbols.  For example,
  28.  
  29.                 SORT <INPUT.DAT >OUTPUT.DAT
  30.  
  31.         causes the SORT filter to read its input from INPUT.DAT, sort
  32.         that data, and place the sorted output into OUTPUT.DAT.
  33.         If you tried
  34.  
  35.                 SORT <INPUT.DAT
  36.  
  37.         SORT would get its input from INPUT.DAT and send the sorted
  38.         data to the screen.
  39.  
  40.         Can you guess what the next line will do?
  41.  
  42.                 SORT >OUTPUT.DAT
  43.  
  44.         That's right, it will read its data from the keyboard and
  45.         send the sorted output to the file OUTPUT.DAT!  This means
  46.         that sort will wait for you to type data, and will continue
  47.         to read your data until you either stop the input with a
  48.         Control-Z (or F6), run out of memory, or turn off the machine!
  49.         After you enter F6, the sorted data will appear on the screen.
  50.  
  51.         For a useful example of this, try
  52.  
  53.                 DIR *.BAS >DIR.LST
  54.                 SORT <DIR.LST >DIRSORT.LST
  55.  
  56.         (There is a neater way to this, which I'll get into soon.)
  57.  
  58.         MORE is a filter, too, with (I presume) some forced reads
  59.         from the keyboard at each pause.
  60.  
  61.         FIND is also a filter, but it can read parms from the command
  62.         line (like MORE should, but doesn't.)  The first parm it
  63.         wants is a search string in double quotes.  The second parm
  64.         is an optional file name.  If you don't supply a filename, FIND
  65.         will read standard input.
  66.  
  67. Now for pipes:
  68.  
  69.         PIPES and FILTERS originally appeared in UNIX.  PIPES are
  70.         much more powerful in UNIX than DOS 2.0, but even ours can
  71.         be very useful.
  72.  
  73.         PIPES, simply put, are several FILTERS strung out with each
  74.         FILTER's output becoming the input to the next.  For example,
  75.         the sorted directory listing in the last example could have
  76.         been produced with
  77.  
  78.                 DIR *.BAS | SORT >DIRSORT.LST
  79.  
  80.         This would result in the same thing but doesn't leave extra
  81.         files hanging around (like DIR.LST in the previous example.)
  82.  
  83.         The "|" (located above the backslash "\" and next to "z") is the
  84.         symbol for a PIPE and is best used with spaces before and
  85.         after.  Sometimes DOS has problems separating the "|" from
  86.         filenames in the parameters and get confused if the "|" is
  87.         not preceeded by a space.
  88.  
  89. ========================================================================
  90.  
  91. Now for the new FILTERS:
  92.  
  93.         UNIX has a large number of very useful FILTERS available, which
  94.         inspired several of the FILTERS here.  What follows is a short
  95.         description of each filter and usage examples for the weirder
  96.         ones.
  97.  
  98. ------------------------------------------------------------------------
  99.  
  100. UPPER & LOWER
  101.  
  102.         These two filters work very much alike - they read from
  103.         standard input and translate every character to either
  104.         uppercase (UPPER) or lowercase (LOWER).  Non-alphabetic
  105.         characters are not affected.
  106.  
  107.         Both of these filters will also accept a filename on the
  108.         command line, which means you don't have to use the redirection
  109.         symbol "<" to supply the input data. Note that output data must
  110.         still be redirected.
  111.  
  112.         Examples:
  113.  
  114.                 UPPER <BOOK.TXT >BOOKUP.TXT
  115.                 LOWER BOOK.TXT >BOOKLOW.TXT
  116.                 UPPER TRASH.TXT
  117.                 etc...
  118.  
  119. ------------------------------------------------------------------------
  120.  
  121. UNIQUE
  122.  
  123.         This filter reads a SORTED list and removes multiple occurances
  124.         of IDENTICAL lines.
  125.  
  126.         Example:
  127.  
  128.                 LOWER BOOK.TXT | TRANSLAT | SORT | UNIQUE >WORDS.TXT
  129.  
  130.         WORDS.TXT new contains a sorted list of all the different words
  131.         contained in BOOK.TXT.
  132.  
  133. ------------------------------------------------------------------------
  134.  
  135. SNGLSPC
  136.  
  137.         This filter reads from standard input and removes blank lines.
  138.         (Blank lines are defined as more than one cr/lf together.)
  139.  
  140. ------------------------------------------------------------------------
  141.  
  142. FEED
  143.  
  144.         This filters accepts a filespec (which can include wildcards!)
  145.         from the command line.  All files which match the filespec
  146.         are opened and the contents are sent to standard output.
  147.         This allows you to redirect the standard input from more than
  148.         one file.  Possible uses are searching a large group of
  149.         files for the occurance of some string, like with FIND.
  150.  
  151.         Example:
  152.  
  153.                 FEED *.FOR | FIND "CALL"
  154.  
  155.         This will find all subroutine calls within a series of programs,
  156.         but, unfortunately, won't necessarily supply the name of each
  157.         file containing the "CALL".
  158.  
  159. ------------------------------------------------------------------------
  160.  
  161. TRUNC
  162.  
  163.         This filter reads a file and truncates it starting at the first
  164.         space or any single character you specify on the command line.
  165.         If the character is not found in the line the entire line is
  166.         passed intact.
  167.  
  168.         Example:
  169.  
  170.                 DIR *.FOR|TRUNC|SORT >FORTRAN.LST
  171.  
  172.         This line will give you a sorted list of fortran programs that
  173.         does not include extensions.
  174.  
  175.                 FEED ???.FOR | FIND "CALL" | TRUNC ( | SORT | UNIQUE
  176.                                                 >FORCALLS.LST
  177.  
  178.         This line fill search all fortran files for the word "CALL",
  179.         truncate each line at the "(" following the subroutine name
  180.         (if any), sort the list, and delete multiple occurances.  This
  181.         gives me a list of all the subroutines called by my programs.
  182.         Note that any numeric labels in the Fortran code are still
  183.         there and result in extra listings at the bottom of the list.
  184.         The next filter takes care of that.
  185.  
  186. ------------------------------------------------------------------------
  187.  
  188. FORCLEAN
  189.  
  190.         This filter reads Fortran files, deletes all comment lines,
  191.         and deletes numeric labels.  Inserting this before the sort
  192.         in th╜╛\Y╗ious TRUNC example eliminates the extra lines
  193.         at the end of the list, as well as comments that happened to
  194.         contain the word "CALL".  I wrote this one to fill a specific
  195.         need, so it will probably not solve any of your problems.
  196.  
  197. ------------------------------------------------------------------------
  198.  
  199. FECHO
  200.  
  201.         This filter is VERY handy when you are designing a filter
  202.         string of your own.  Placing it in your command allows you to
  203.         see what is going on without disrupting the command itself.
  204.         Specificaly, it reads standard input and sends the data to both
  205.         standard output AND error out